feat: adding JSON overview and Json configuration docs #3102
Conversation
|
|
||
| The Kotlin serialization library allows you to easily convert Kotlin objects to JSON and back. | ||
| The [`Json`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/) class is the primary tool for this, offering flexibility in how JSON is generated and parsed. | ||
| You can configure `Json` instances to handle specific JSON behaviors or use it without any changes for basic tasks. |
There was a problem hiding this comment.
Maybe use words like use its default instance? Otherwise it is unclear what to use, because Json class does not have a public constructor on its own.
|
|
||
| * Serialize Kotlin objects to JSON strings using the [`encodeToString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/encode-to-string.html) function. | ||
| * Deserialize JSON strings back to Kotlin objects with the [`decodeFromString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/decode-from-string.html) function. | ||
| * Work directly with the [`JsonElement`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/) when handling complex JSON structures using the [`encodeToJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/encode-to-json-element.html) and the [`decodeFromJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/decode-from-json-element.html) functions. |
There was a problem hiding this comment.
I see we can nicely add encodeToStream/decodeFromStream to the list here. IMO it's OK to add a separate page for them + Okio integration
|
|
||
| * Serialize Kotlin objects to JSON strings using the [`encodeToString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/encode-to-string.html) function. | ||
| * Deserialize JSON strings back to Kotlin objects with the [`decodeFromString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/decode-from-string.html) function. | ||
| * Work directly with the [`JsonElement`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/) when handling complex JSON structures using the [`encodeToJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/encode-to-json-element.html) and the [`decodeFromJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/decode-from-json-element.html) functions. |
There was a problem hiding this comment.
Should we give the link to serialization-json-elements.md here instead of API reference for JsonElement? IMO guides are easier to read than plain reference.
| * Deserialize JSON strings back to Kotlin objects with the [`decodeFromString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/decode-from-string.html) function. | ||
| * Work directly with the [`JsonElement`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/) when handling complex JSON structures using the [`encodeToJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/encode-to-json-element.html) and the [`decodeFromJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/decode-from-json-element.html) functions. | ||
|
|
||
| Before you start, import the following declarations from the serialization libraries: |
There was a problem hiding this comment.
Given that we do not make a lot of emphasis on the fact that -core and -json are separate, maybe it is better to just use "serialization library"
| Here's a simple example that demonstrates how JSON serialization works in Kotlin: | ||
|
|
||
| ```kotlin | ||
| // Imports declarations from the serialization and JSON handling libraries |
There was a problem hiding this comment.
Same here. IMO "Imports declarations from the serialization library" is enough
|
|
||
| ### Encode default values | ||
|
|
||
| By default, the JSON serializer doesn't encode default property values because they are automatically applied to missing properties during decoding. |
There was a problem hiding this comment.
| By default, the JSON serializer doesn't encode default property values because they are automatically applied to missing properties during decoding. | |
| By default, the JSON format doesn't encode default property values because they are automatically applied to missing properties during decoding. |
(to avoid confusion with KSerializer instances, to which we usualy refer as serializers)
| ``` | ||
| {kotlin-runnable="true"} | ||
|
|
||
| > [`@JsonClassDiscriminator`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-class-discriminator/) is [Experimental](components-stability.md#stability-levels-explained). To opt in, use the `@OptIn(ExperimentalSerializationApi::class)` annotation or the compiler option `-opt-in=kotlinx.serialization.ExperimentalSerializationApi`. |
There was a problem hiding this comment.
Experimentality warning about JsonClassDiscriminator before introducing JsonClassDiscriminator itself is strange. This block should be moved one paragraph down.
| > | ||
| {style="note"} | ||
|
|
||
| #### Set class discriminator output mode |
There was a problem hiding this comment.
I think this setting is important (and distinct) enough to have ### header — so it can be found in navigation as well
|
|
||
| fun main() { | ||
| // Decodes a JSON string with lenient parsing | ||
| // Lenient parsing allows unquoted keys, string and enum values, and quoted integers |
There was a problem hiding this comment.
| // Lenient parsing allows unquoted keys, string and enum values, and quoted integers | |
| // Lenient parsing allows unquoted keys, string and enum values. |
(we allow quoted integers without this flag too)
There was a problem hiding this comment.
We even have Note that parsing of quoted numbers or booleans such as votes: "9000" to val votes: Int is generally allowed by kotlinx.serialization regardless of the isLenient flag, since such JSON is syntactically valid. note below
| > | ||
| {style="note"} | ||
|
|
||
| ## Customize JSON deserialization |
There was a problem hiding this comment.
We have a pair of new flags that aren't in docs yet: allowTrailingComma and allowComments. Can you take care of them, please? (they won't be experimental in next release)
This is the fifth part of the Kotlin Serialization rewrite task.
Related Youtrack ticket: KT-81979